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SCOrE  AND  PURPOSE 


1 . 1 C1ENERAL 

1.1.1  This  specification  defines  the  requirements  for  each  of  the 
deliverable  items  of  a computer  program,  including  the  associated 
documentation  items.  This  specification  also  defines  the  precise 
relationship  between  the  items  that  are  required  for  understanding 
tlie  program  and  for  accessing  data  within  each  document. 

1.1.1  Additionally,  the  specification  defines  the  requirements  for 
configuration  control  of  each  item  to  permit  tracing  of  the  pro- 
gram evolution  through  the  complete  program  life  cycle.  The  precise 
configuration  control  specified  will  permit  the  simultaneous  exist- 
ence of  two  or  more  configurations  during  the  evolutionary  process. 
Multiconfiguration  is  the  by-product  of  a dynamic  tactical  situation 
and  the  constant  pressure  to  improve  systems  effectiveness. 

1.1.3  To  accomplish  these  goals,  data  items  are  required  to 
document  each  process  in  the  program  life  cycle — from  design, 
through  coding  and  testing,  to  the  permanent  documentation  required 
for  training  of,  and  field  use  by,  personnel  who  must  be  rotated 
regularly  because  of  other  military  constraints.  Additionally,  the 
data  items  must  be  compatible  with  revision  processes  that  will 
result  inevitably  from  knowledge  gained  from  Fleet  use  and  from 
Improvements  in  the  state  of  the  art  of  the  equipment  deployed  in 
the  Fleet. 

1.1.4  The  required  data  items  are  listed  subsequently;  their 
contributions  to  the  overall  program  and  some  of  the  reasons  for 
their  existence  are  provided  in  the  following  paragraphs. 

(a)  Document  Control  List 

(b)  Program  Flow  Diagrams 

(c)  Functional  Description  of  Logic  Flow 

(d)  Functional  Specification 

(e)  Functional  Flow  Charts 

(f)  Program  Card  Deck 
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(g)  Source  Program  Listing 

(h)  Assembled  Program  Listing 

(i)  Testing  Routines 

( j ) Program  Tape 

1.2  DOCUMENT  CONTROL  LISTING 

1.2.1  To  control  the  evolutionary  process  from  tactical  requirement 
to  operational  program,  a document  control  numbering  system  has  been 
established  and  is  described  in  Section  3.1.16,  Data  Management 
Control  Block.  This  system  has  a logical  structure  such  that  the 
same  types  of  documents  (i.e.,  operational  specifications)  will  have 
similar  numbers,  and  all  documents  of  a specific  configuration  will 
have  related  nvunbers.  The  evolu'f'lon  of  the  control  nixmbers  must  be 
documented  formally  and  maintained.  Toward  this  end,  the  require- 
ments for  a Document  Control  List  have  been  established. 

1.3  PROGRAM  PLOW  DIAGRAMS  AND  FUNCTIONAL 
DESCRIPTION  OP  LOGIC  PLOW 

1.3.1  Program  Flow  Diagrams  and  Functional  Description  of  Logic 
Flow  are  designed  jointly  to  document  the  program  design  portion  of 
the  program  life  cycle.  Since  the  personnel  who  perform  the  pro- 
gram design  are  normally  separate  from  the  personnel  who  perform 
the  coding  task,  it  is  necessary  that  the  logic  and  technique  used 
by  the  program  designer  be  documented  in  some  permanent  fashion. 

Such  a permanent  record  is  mandatory  because  there  may  be  a con- 
siderable time  lapse  between  the  design  of  the  program  and  its  final 
loading  and  field  use;  or  because  of  advancement,  reassignment 
within  the  company,  or  relocation  to  a new  or  different  company, 

the  program  designer  may  not  be  available  to  explain  or  defend  the 
design  of  the  program.  Toward  this  end,  the  illustration  of  the 
logic  and  the  functional  grouping  of  logic  by  use  of  a Program  Plow 
Diagram,  and  the  narrative  description  of  the  parameters  surround- 
ing the  logic  by  use  of  the  Functional  Description  of  Logic  Flow, 
were  developed. 
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l.A.l  Since  the  personnel  who  code  the  program  are  organizationally 
;md  sometimes  geographically  separate  from  the  personnel  who  design 
the  program,  a vehicle  of  communication  is  necessary  to  bridge  the 
gap.  To  accomplish  this,  the  Program  Flow  Diagrams  and  the  Func- 
tional Descriptions  developed  during  program  design  are  reviewed, 
corrected,  and  finalized  at  the  critical  design  review  at  the  com- 
pletion of  the  Logic  Design  Phase.  Following  approval,  the  Func- 
tional Descriptions  of  Logic  Flow  are  renamed  and  become  the 
Functional  Specification,  which  is  a binding  document  during  the 
coding  of  a program.  Finally,  but  no  less  important,  it  may  not  be 
apparent  which  portion  of  the  coding  corresponds  precisely  to  a 
specific  portion  of  the  logic  design.  Hence,  the  subfunctional 
grouping  technique  of  the  Program  Flow  Diagram  is  provided  as  a firm 
base  for  reference  between  not  only  the  coding  and  the  Program  Flow 
Diagram,  but  between  all  levels  of  data  items. 

1.5  FUNCTIONAL  PLOW  CHART 

1.5.1  The  Functional  Plow  Chart  is  the  programmer's  illustration 
of  the  technique  used  to  make  the  computer  at  hand  satisfy  the 
requirements  of  the  program  design. 

1.5.2  The  Functional  Flow  Charts  are  similar  in  design  and  content 
to  the  Program  Flow  Diagram]  they  illustrate  the  programmer's 
approach  to  the  coding  process,  rather  than  the  designer's  interpre- 
tation of  the  Operational  Specification.  The  flow  charts  illus- 
trate how  the  program  satisfies  the  requirements  of  the  design,  and 
the  actual  sequence  of  events  that  occurred  in  the  coding  process, 
rather  than  the  options  available  as  Illustrated  by  the  Program 
Plow  Diagram.  The  Functional  Plow  Charts  will  be  used  for  personnel 
training  and  for  Fleet  documentation,  v/hlle  the  Program  Flow  Dia- 
grams shall  be  maintained  as  a base  for  future  revisions  to  the 
design  of  the  programs. 
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1.6  PROGRAM  CARD  DECK  AND  SOURCE 
PROGRAM  LISTING 

1.6.1  These  documents  record  the  program  coding  portion  of  the 
program  life  cycle.  Additionally,  through  the  use  of  Identifying 
numbers  on  the  comment  cards,  they  provide  a precise  reference  to 
the  Program  Plow  Diagram  which  documents  the  portions  of  the  logic 
design  requirements  being  satisfied  by  coding.  The  requirement  for 
Identification  of  the  subfvinctlonal  breakdown  of  the  coding  provides 
a facility  for  identification  of  the  portion  of  the  coding  that 
satisfies  the  logic  requirements  Illustrated  on  the  Program  Flow 
Diagrams . 

1.6.2  To  accomplish  this  Identification  task,  the  requirements 
for  comment  cards  was  instituted.  ^ use  of  comment  cards  which  do 
not  affect  the  compilation  or  njnning  of  the  program,  the  subsec- 
tions of  the  card  deck  and  the  program  listing  can  be  Identified 
and  their  purpose  described. 

1.6.3  This  identification  and  logic  description  is  a good  general 
practice  for  all  programming,  and  specifically  desirable  for  mili- 
tary computer  programs.  The  identification  and  description  Is 
extremely  valuable  during  the  debugging  process. 

1.6.4  With  the  constant  pressure  to  improve  the  program  generally, 
and  to  change  the  program  to  meet  changing  tactical  requirements, 
it  is  imperative  that  complete  visibility  and  access  be  provided  to 
the  various  portions  of  the  program  by  the  comment  cards.  With  the 
visibility  and  access  provided,  proposed  changes  can  be  analyzed 
effectively  for  Impact  on  the  program,  and,  as  necessary,  programs 
can  be  updated  more  easily  to  meet  the  tactical  requirements. 

1 . 7 testing  routines 

1.7.1  The  requirements  for  testing  are  self-evident;  some  of  the 
associated  problems,  however,  are  not.  Testing  is  divided  into  two 
categories;  (1)  Logical  Testing  (debugging)  which  is  performed  to 
ensure  that  the  program  will  run;  and  (2)  Simulation  Testing  which 
is  performed  to  ensure  that  the  program  will  meet  the  mission 
requirements. 
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1.7.2  Debugging  is  an  Important  part  of  the  computer  programming 
process,  It  is  unlikely  that  the  first  attempt  at  running  any  pro- 
gram will  be  successful.  Since  the  probability  of  error  is  high, 
the  precise  documentation  technique  discussed  in  the  previous  para- 
graphs will  be  extremely  advantageous  to  the  contractor  developing 
the  program.  V/hile  the  program  is  being  debugged  the  Program  Card 
Deck  will  be  changed.  It  is  imperative  that  the  Program  Flow  Dia- 
grams, Functional  Description,  comment  cards,  etc.,  be  updated  to 
reflect  these  changes. 

1.7.3  Logical  Testing  Routine 

1.7. 3.1  To  ensure  that  the  program  will  run.  Logical  Testing 
Routines  which  exercise  the  logic  of  the  program  routines  roust  be 
developed.  With  these  routines  available,  program  routines  can  be 
checked  out  as  they  are  coded,  thus  reducing  the  debugging  burden 
near  the  final  delivery  milestone. 

1.7.^  Simulation  Testing  Routine 

1.7.4. 1 To  ensure  that  the  program  will  accomplish  its  Intended 
task,  a testing  routine  which  simulates  the  operational  environment 
and  contains  realistic  data  must  be  developed.  Ultimately  the  pro- 
gram will  be  Fleet  tested  to  ensure  that  a program  will  meet  Fleet 
requirements . 

1.8  SUMMARY 

1.8.1  The  specification  provides  precise  requirements  for  the 
development  and  control  of  the  necessary  programming  information 
associated  with  computer  software  production.  Each  documentation 
device  has  been  carefully  designed  to  meet  a specific  need,  and  to 
have  a specific  relationship  to  the  other  documentation  devices. 
Quality  control  requirements  have  been  established  and  will  be 
adhered  to.  By  use  of  these  docvimentatlon  techniques  and  by  careful 
attention  to  technical  accuracy  and  consistency,  satisfactory  com- 
puter program  documentation  will  result.^ 
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.'.I  COVERNMENT  DOCUMENTS 

Tl'io  rollowint’;  government  document  (n ) , of  the  Issue  In  r;ffoet 
on  itati;  of  Invitation  for  bide  or  request  for  proposal,  form  a part 
of  l.lils  specification  to  the  extent  specified  herein. 

MIL-STD-682,  Plow  Chart  Symbols  for  ADP  Systems 

(Copies  of  specifications,  standards,  drawlnp.s,  and 
publications  required  by  suppliers  in  connection  with 
specific  procurement  functions  should  be  obtained 
from  the  procurlnf’;  activity  or  as  dlrccteci  by  the  con- 
tracting’; officer. ) 

Naval  Tactical  Data  System,  CS-l  Manual. 
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3.  REQUIREMENTS 


3.1  PROGRAM  FLOW  DIAGRAMS  AND  FUNCTIONAL  FLOW  CHARTS 

3.1.1  This  subsection  specifies  the  requirements  for  preparing  the 
graphic  representations  that  illustrate,  on  a single  sheet,  the 
logical  flow  of  data  and  the  sequence  of  operations  in  a digital 
computer  program,  routine,  or  subroutine,  through  the  use  of  geo- 
metric shapes,  symbols  and  supplementary  notations.  Unless  other- 
wise noted,  all  requirements  of  this  section  apply  equally  to  both 
types  of  diagrams.  The  style  and  format  remain  the  same,  only  the 
level  of  detail  varies.  The  two  types  of  graphic  documentation 
required  by  this  specification  are  described  below. 

3.1.2  Program  Flow  Diagram 

3. 1.2.1  The  Program  Flow  Diagram  (see  Figure  1)  is  the  basic 
document  illustrating  the  decision  processes,  and  resulting  actions 
in  terms  of  design  logic.  The  design  logic  includes  tests  such  as 
"target  closer  than  200  miles",  "target  displaying  IFF",  "target 
confirmed",  and  actions  such  as  Set;  Drop  Track  ELt;  Subtract  Range 
from  Previous  Range;  Compute;  New  Target  Position.  When  multiple 
actions  are  to  be  performed  after  a test  or  series  of  tests, 
optional  sequences  must  be  identified  to  provide  flexibility  in  the 
programming  process.  With  the  options  illustrated,  the  programmer 
can  attempt  various  combinations  to  Improve  the  efficiency  of  the 
program. 

3.1.3  Functional  Flow  Chart 

3. 1.3.1  A detailed  extension  of  the  Program  Flow  Diagram,  the 
Functional  Flow  Chart,  Illustrates  the  programming  process  required 
to  satisfy  the  logic  design  requirements  of  the  Program  Flow  Diagram, 
and  the  options  selected.  Figure  2 provides  an  example  of  a 
Functional  Flow  Chart. 

3. 1.3. 2 In  addition  to  containing  blocks  for  each  logical  decision 
and  action,  the  Functional  Flow  Chart  shall  contain  blocks  for 
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programming  operations  such  as  masking,  shifting.  Incrementing, 
clearing,  storing,  exclusive  orlng,  etc. 

3. 1.3. 3 The  terminology  In  the  decision  and  action  boxes  shall 
reflect  the  coding  of  the  requirements  Illustrated  on  the  Program 
Plow  Diagram.  For  example,  where  the  Program  Flow  Diagram  Illus- 
trates "Set  Drop  Track  Bit",  the  Functional  Plow  Chart  Illustrates 
"Set  DT=l"  where  DT  has  been  defined  as  the  word  section  or  table 
that  contains  drop  track  Information. 

3.1.3.^  Computer  prepared  Functional  Plow  Charts  shall  comply  with 
the  following  requirements  for  content,  but  shall  be  exempted  from 
the  requirements  for  format. 

3.1.^  Preparation 

3. 1.4.1  A Program  Flow  Diagram  and  Functional  Plow  Chart  shall  be 
prepared  for  each  of  three  program  subdivisions — one  Illustrating 
the  division  of  the  complete  program  Into  routines,  one  Illustrat- 
ing the  division  of  a routine  Into  subroutines,  and  one  illustrat- 
ing the  flow  within  each  of  the  subroutines. 

3.1.5  Degree  of  Detail 

3. 1.5.1  The  degree  of  detail  Is  Influenced  by  the  problem,  by  the 
programming  language  to  be  used,  and  by  the  level  of  program  sub- 
division being  flow-charted.  Flow  diagrams  that  deal  with  low-level 
program  subdivisions  require  more  detail  than  flow  charts  that  deal 
with  the  higher  levels. 

3. 1.5. 2 Overall  Program  Flow  Diagram  and  Overall  Functional  Flow 


3. 1.5. 2 Overall  Program  Flow  Diagram  and  Overall  Functional  Flow 
Chart . The  overall  Program  Plow  Diagram  and  Overall  Functional 
Flow  Chart  shall  contain  one  block  for  each  major  routine.  They 
shall  have  one  block  for  each  peripheral  device  which  provides 
Input  to,  or  receives  output  from,  the  computer  being  programmed. 
They  shall  have  lines  connecting  the  boxes  to  Illustrate  the  flow 
within  the  program,  with  separate  lines  to  be  used  for  each  basic 
flow.  When  direction  of  flow  Is  not  readily  apparent,  arrowheads 
shall  be  used  to  Indicate  direction  of  flow. 


j . 1 . 'j . 3 Ma.ior  Routine  Proj^^ram  Flow  Diagrams  and  Functional  Flow 
Chart . These  Major  Routine  Program  Flow  Diagrams  and  Functional 
Flow  Charts  shall  contain  one  block  for  each  subroutine  which  will 
bo  Illustrated  by  a separate  diagram.  They  shall  also  contain 
decision  symbols,  where  applicable,  to  illustrate  decision  criteria 
for  entry  into  the  subroutine.  Flow  lines  shall  be  used  to  illus- 
trate flow  between  the  subroutines.  Where  direction  of  flow  is  not 
readily  apparent,  arrowheads  shall  be  used  to  indicate  direction 
of  flow. 

3.1.5.'4  Subroutine  Pi^ogram  Flow  Diagrams  and  Functional  Flow 
Chart . The  subroutine  Program  Plow  Diagrams  and  Functional  Plow 
Charts  shall  Illustrate,  by  appropriate  programming  symbol,  each 
individual  decision,  each  Individual  action  to  be  performed  in  the 
process  Illustrated  by  the  diagrams,  and  the  tie-ins  to  the  sub- 
functional  diagram(s)  that  produced  the  input  and  received  the 
output . 

3. 1.5*5  NTjmberlng  Technique.  Each  grouping  block  at  each  level 
shall  have  an  identifying  number.  Decimal  indenture  shall  be  used 
to  indicate  subordination  of  groupings.  New  routines  shall  be 
identified  by  name  only.  Numbers  between  the  first  and  second  deci- 
mal shall  indicate  the  major  subroutines  within  the  major  routines. 
Numbers  between  the  second  and  third  decimal  shall  Indicate  sub- 
routines within  the  major  subroutines.  Additional  subordinate 
numbering  shall  be  used  as  required  to  Identify  the  subordinate 
groupings  within  the  subroutines.  An  example  of  the  numbering 
technique  is  provided  in  Figure  1 . 

3.1.6  Standard  Symbols 

3. 1.6.1  The  standard  symbols  in  MIL-STD-682  shall  be  used  in  the 
preparation  of  flow  charts  (machine  generated  diagrams  excepted). 
These  symbols  shall  not  be  redefined,  nor  other  symbols  substituted 
for  the  defined  functions.  If  additional  symbols  for  functions  not 
defined  are  required  for  a specific  application,  such  additional 
symbols  may  be  used,  provided  the  procuring  agency  has  approved 
their  use. 
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^.1.7  SymlDol  Template 

3. 1.7.1  All  of  the  standard  symbols  can  be  dravm  with  the  aid 
of  the  standard  symbol  template  specified  in  MIL-STD-682.  The 
template  should  be  used  in  the  preparation  of  all  flow  charts. 
Symbols  available  on  the  standard  template  are  illustrated 
by  Figure  3. 
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3.1.8  Program  Flow  Diagram  and  Functional 
Flow  Chart  Symbols 

3. 1.8.1  Symbols  are  used  on  Program  Flow  Diagrams  and  Functional 
Floxi?  Charts  to  represent  the  functions  of  a data  processing  program 
or  system.  Basic  symbols  are  established  for  the  basic  functions 
that  are  ordinarily  Included  in  high-level  flow  charts;  l.e.,  input/ 
output,  processing,  and  annotation.  Specialized  symbols  are  estab- 
lished for  the  detailed  functions  that  are  ordinarily  included  in 
low-level  (subroutine)  flow  charts. 

3. 1.8. 2 Basic  Symbols.  The  basic  symbols  are  as  follows: 

(a)  Input/Output  Symbol.  The  symbol  shown  below  represents 
the  basic  Input/output  function  (I/O);  l.e.,  the  making  available 
of  data  for  processing  (input),  or  the  recording  or  displaying  of 
processed  data  (output). 


fe 


(b)  Processing  Symbol.  The  symbol  shown  below  represents  the 
basic  processing  function;  l.e.,  the  process  of  executing  a defined 
operation  resulting  in  a change  in  value,  form,  or  location  of  data. 


(c)  Annotation  Symbol.  The  symbol  shown  below  represents  the 
basic  annotation  function;  i.e.,  the  addition  of  descriptive  com- 
ments or  explanatory  notes  as  clarification.  The  dotted  line  may 
be  drawn  either  on  the  left  aind  down  (as  shown),  on  the  right  and 
down,  on  the  top  and  left,  or  on  the  top  and  right.  It  is 
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connected  to  the  flowline,  at  a point  where  the  einnotation  is 
meaningful,  by  extending  the  broken  line  in  whatever  manner  is 
appropriate . 


3. 1.8.3  Specialized  Symbols.  The  specialized  symbols  are  as 
follows : 

(a)  Input/Output  Symbols.  The  specialized  input /output 
symbols  represent  the  I/O  fimction  and,  in  addition,  denote  the 
medium  on  which  the  data  is  recorded  or  displayed  or  manner  of 
handling  data,  or  both.  The  input/output  symbols  are: 


(1)  Data  Card  Symbol.  The  symbol  below  represents  an 
I/O  function  in  which  the  medium  is  punch  cards,  or  the  like.  The 
symbol  also  represents  a card  file. 


Symbol 


Typical  Use 

>J 


I Payroll  Data| 

^ ■ ■ “I 


(2)  Itognetic  Tape  Symbol.  The  symbol  shown  below 
represents  an  I/O  function  in  which  the  medium  is  magnetic  tape. 


Symbol 


Typical  Use 
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(3)  Punch  Tape  Symbol.  The  symbol  shown  below  represents 
an  I/O  function  in  which  the  medi\im  is  punch  tape. 


Punch  Tape  Symbol 


Typical  Use 


(4)  Printed  Document  Symbol 
an  I/O  fvinctlon  in  which  the  medium  is 


The  symbol  below  represents 
a machine  printed  docment. 


Symbol  Typical  Use 

I 


Correlation 

Data 

(5)  Manual  Input  Symbol.  The  symbol  shown  below 
represents  an  I/O  function  in  which  the  data  is  entered  manually  at 
the  time  of  processing,  by  means  of  on-line  keyboards,  switch  set- 
tings, push  buttons,  etc. 

Portion  of  Symbol  Typical  Use 


1 


i 

i 


\ 


NOTE 

This  symbol  can  be  drawn  with  the  template,  but 
it  is  not  defined  as  a Military  Standard  symbol. 


! 


A 
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(6)  Display  Symbol.  The  symbol  shown  below  represents 
an  I/O  function  in  which  the  data  is  displayed  for  human  use  at  the 
time  of  processing,  by  means  of  on-line  printers,  console  printers, 
video  devices,  plotters,  etc. 


Portion  of  Symbols 


Typical  Use 


(7)  Mass  Storage  Symbol.  The  symbol  shown  below 
represents  an  I/O  function  utilizing  auxiliary  mass  storage  of  data 
that  can  be  accessed  on-line,  e.g.,  magnetic  drums,  magnetic  discs, 
or  other  computer. 


Symbol 


Typical  Use 


(b)  Processing  Symbols.  The  specialized  processing  symbols 
represent  the  processing  function,  and  in  addition  identify  the 
specific  type  of  operation  to  be  performed  on  the  data.  The  proc- 
essing symbols  are: 

(1)  Decision  Symbol.  The  symbol  shown  below  represents 
a decision  type  operation  that  determines  which  of  two  or  more 
alternate  paths  is  to  be  followed.  This  symbol  may  contain,  upon 
option,  a horizontal  subdivision  line  near  the  bottom,  below  which 
may  be  entered  pertinent  or  informative  data  such  as  the  data  unit 
on  which  the  decision  is  made,  an  input  or  output  condition,  or  a 
sense  switch  setting. 
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Symbol  Normal  Decision  Use 


represents  a switching  type  of  operation,  e.g.,  the  routing  of  input 
data  to  either  of  two  output  paths  depending  upon  the  setting  of 
the  switch,  either  "set"  (S)  or  "normal"  (N). 


(3)  Subroutine  Symbol.  The  symbol  below  represents  a 
reference  to  a subroutine.  This  symbol  may  contain,  upon  option,  a 
horizontal  division  line  near  the  bottom,  below  which  pertinent  or 
informative  data  may  be  entered;  e.g.,  the  subroutine  label. 


3-9 


!| 


i 


i ’ 
♦ 


(4)  Manual  Operation  Symbol.  The  symbol  shown  below 
represents  any  off-line  process  geared  to  the  speed  of  a human 
being. 

Symbol  Typical  Use 


(5)  Auxiliary  Equipment  Operation  Symbol.  The  symbol 
shown  below  represents  an  off-line  operation  performed  on  equip- 
ment not  under  direct  control  of  the  central  processing  unit. 

Symbol  Typical  Use 


Punch 

Data 


(6)  Non- Auxiliary  Equipment  Operation  Symbol.  The 
symbol  shown  below  represents  an  on-line  operation  performed  on 
equipment  under  direct  control  of  the  central  processing  vinlt. 

This  symbol  may  contain,  upon  option,  a horizontal  subdivision  line 
near  the  bottom,  below  which  may  be  entered  pertinent  or  Informative 
data,  such  as  names  of  data  being  processed. 


i 


l! 


Symbol 


Typical  Use 


or 

Computer 

Elevation 


ELDAT 


3. 1.8.4  Assertion  Symbol.  The  symbol  shown  below  Indicates  a 
special  condition  existing  at  a certain  point  along  a flow  line. 

Symbol  Typical  Uses 


I 

I 


N = 100 


Simulate 


3. 1.8. 5 Insertion  Symbol.  The  symbol  shown  below  Indicates  the 
Insertion  of  a processing  symbol  into  a flow  line;  the  single  line 
drawn  to  the  symbol  represents  both  the  Input  line  and  the  output 
line. 


Symbol 


Typical  Uses 


This  symbol  Is  intended  for  use  in  updating 
flow  charts  and  should  not  appear  in  any  final 
flow  chart. 
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3. 1.8.6  Communication  Link  Symbol.  The  symbol  shown  below 
represents  an  I/O  function  In  which  data  Is  transmitted  automati- 
cally from  one  location  to  another.  The  symbol  shall  always  be 
drawn  with  arrowheads  to  denote  the  directions  of  data  flow. 

Symbol  Typical  Uses 


! 

i 


One  arrowhead  Indicates 
unidirectional  flow. 


Two  arrows  indicate 
bidirectional  flow. 


3.1.9  Symbol  Sizes 

3. 1.9.1  When  reduced  50  percent,  the  size  of  each  symbol  shall  be 

I as  illustrated  on  the  sample  block  diagrams.  The  sizes  illustrated 

on  the  template  are  considered  appropriate  for  the  "up"  or  non- 
reduced  size  preparation  of  any  flow  chart. 

' 3.1.10  Symbol  Orientation 

3.1.10.1  All  of  the  symbols  shall  be  oriented  as  illustrated  in 
Figure  1,  Program  Flow  Diagram  for  Height  Processing  Routine,  and 
Figure  2,  Functional  Flow  Chart  for  Height  Processing  Routine. 

3.1.11  Symbol  Grouping 

3.1.11.1  Symbols  shall  be  grouped  functionally  to  illustrate 
subfunctional  actions  and  to  illustrate  the  relationships  between 
the  subf\anctional  actions.  Groupings  shall  be  selected  to  have  a 

' single  input  and  two  outputs  as  illustrated  in  Figure  1.  Two  basic 

, groupings  are  required  in  the  subroutine  flow  diagram  to  Illustrate 

; the  subroutine  and  to  facilitate  the  preparation  of  and  reference 

I to  the  fiinctlonal  descriptions.  These  are: 

I (a)  Grouping  of  decision  groupings  and  associated  action 

, i groupings  that  form  an  Identifiable  s ub- sub rout ine . 

! 


J 

j 

1 


I 
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(b)  Grouping  the  identifiable  sub-subroutines  into  higher 
order  subroutines. 

Individual  decision  symbols  which  control  the  entry  into  one  or 
another  sub-subroutine  need  not  be  contained  in  a box. 

3.1.12  Flow  Lines 

3.1.12.1  Plow  lines  on  the  Program  Flow  Diagram  will  be  controlled 
to  Illustrate  the  sequence  to  be  followed  by  the  programmer  during 
the  coding  process.  To  facilitate  the  coding  process,  both  the 
fixed  sequences  and  the  optional  sequences  must  be  illustrated 
clearly  on  the  Program  Flow  Diagram  as  follows: 

(a)  Actions  which  must  be  performed  sequentially: 


Set : 

Set: 

Set: 

Track  to  Establish 

Symbol  Change  Bit 

Track  to  Establish 

(b)  Actions  which  must  be  performed  at  this  time  in  the 
program  but  can  be  performed  in  any  sequence.  (The  person  doing  the 
coding  may  find  an  opportvuaity  to  improve  program  efficiency  by 
changing  the  sequence  of  action. ) 


1 
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(c)  Sequences  of  actions  which  may  be  performed  in  optional 


sequence : 


Calculate : 


'‘'v,  - 1 = d, 

n n- 1 


Calculate: 

S = Y^-1  - "n-l 


Calculate ; 

= ’'n-l  - ^n-1 


Calculate : 

d = Y 1 - , 

X n-1  n-1 


Calculate: 

d = Y - Y , - d 
X n n-1 


Calculate 

‘^x  = ^n-l  - ^n-l 


On  Functional  Flow  Charts  option  sequence  is  prohibited,  since 
these  charts  illustrate  the  order  in  which  the  options  were 
exercised. 

3.1.12.2  Flow  lines  will  be  controlled  to  Illustrate  "and"  and 
"or"  types  of  decision  actions  as  follows; 

(a)  "Or  Decision": 


Track 

Quality 

Test 


N 


ck  \ f Track  'y 
ity  ; p/  Quality  J 

' yrv  j 


r Track 

Quality 


On  Program  Flow  Diagrams  the  Illustration  implies  optional  sequence 
On  Functional  Plow  Charts,  the  actual  testing  sequence  is  left  to 
right,  with  the  first  test  provided  in  left  symbol. 


3.1.12.3  Straight  lines,  vertical  or  horizontal,  shall  he  used  to 
show  the  flow  of  control  or  of  data  between  the  symbols  on  a flow 
diagram.  Symbols  requiring  two  output  lines  shall  normally  have 
both  output  lines  perpendicular  to  the  input  line.  None  of  the 
lines — input  or  output — are  considered  to  be  inherently  the  part  of 
any  symbol. 

3.1.12.4  Connection  of  the  lines  to  the  grouping  boxes  are 
indicative  of  program  sequence.  Lines  passing  left  to  right  through 
a grouping  box  indicate  that  the  decision  or  action  listed  in  the 
box  must  be  performed  before  the  program  can  proceed.  Lines  enter- 
ing a grouping  box  from  the  top,  or  lines  entering  a grouping  box 

at  the  left,  with  no  line  departing  the  right  of  the  box,  indicate 
an  action  that  must  be  performed  at  this  time,  but  that  subsequent 
program  operations  within  this  subroutine  are  not  dependent  on  the 
results  of  the  action. 
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3.1.13  Direction  of  Flow 

3.1.13.1  Horizontal  flow  dlagrairanlng  Is  required.  All  direction 
of  flow  of  Inputs  and  outputs  Is  left-to-rlght,  unless  otherwise 
Indicated.  Properly  oriented  directional  arrowheads  may  be  placed 
anywhere  along  a flow  line. 

3.1.14  Notations 

3.1.14.1  Internal  consistency  Is  of  prime  Importance  In  Program 
Flow  Diagram  and  Functional  Flow  Chart  preparation.  To  avoid  a 
hodgepodge  appearance,  a few  rules  must  be  observed.  These  are: 

(a)  All  text  words  shall  have  Initial  capitals,  with  the 
remaining  letters  In  lower  case. 

(b)  References  to  programs  and  to  data  units,  when  they  are 
the  names  used  In  the  computer  program,  shall  be  in  all  capital 
letters . 

(c)  References  to  hardware  labels  shall  be  as  fovind  on  the 
hardware . 

(d)  No  question  mark  shall  be  placed  at  the  end  of  the  text 
in  a decision  boxj  the  symbol  itself  indicates  a question. 

(e)  Text  shall  be  condensed  so  as  to  fit  within  the  symbols, 
but  abbreviations  avoided.  If  possible. 

(f)  Minimize  mathematical  notation  unless  expressing  complete 
equations.  Where  possible,  text  shall  be  in  ordinary  English  in 
terms  that  can  be  easily  vinderstood. 

(g)  Questions  shall  be  phrased  (in  decision  boxes)  so  that 

they  can  be  answered  with  a "Yes"  or  "No".  Other  responses  are 
permissible;  e.g.,  , , =,  eind  combinations  thereof.  If  the 

decisions  are  expressed  In  English  words,  the  first  letter  of  each 
word  shall  be  capitalized. 

(h)  Action  Illustrated  by  an  action  box  shall  be  indicated  by 
a statement  of  the  action  In  the  upper  left  corner  of  the  box; 
l.e..  Set:,  Subtract:,  Compute:,  Increment;,  etc.  The  action  to  be 
performed  shall  be  Indicated  on  the  following  lines  within  the  box. 
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3.1.15  Subroutine  Grouping 

3.1.15.1  Major  routines  within  the  program  may  have  single  Input 
and  single  output,  or  single  Input  and  two  outputs.  Major  routines 
shall  be  subgrouped  as  illustrated  In  Figure  4 to  Identify  the  sub- 
routines within  the  major  routine,  and  to  Illustrate  the  relation- 
ship and  flow  between  the  subroutines. 

3.1.16  Data  Management  Control  Block 


3.1.16.1  Each  diagram  shall  have  a data  management  control  block.  j 
The  basic  identifying  number  (first  eight  digits)  will  be  assigned  i 
by  FCPC.  The  drawing  control  number  (next  four  digits)  are  assigned  ' 
by  the  contractor  and  recorded  with  TDS  Computer  Program  Manager's  I 
Documentation  Library.  The  first  two  digits  of  the  document  control  ^ 
number  shall  indicate  the  major  routine  (01  through  99) J the  second  i 
two  digits  shall  indicate  the  subroutine  (01  through  99)  within  the  | 
routine . 


3.1.16.2  The  fifth  digit  identifies 

1 — Operational  Specification 

2 — Program  Flow  Diagram 

3 — Functional  Description  of 

Logic  Flow 

4 — Functional  Flow  Chart 


the  type  of  document  as  follows: 

5 — Program  Routine 

6 — Test  Routine 

7 — Program  Listing 

8 — Assembly  Listing 

9 — Simulation  Program 


i 

j 

i 


3.1.16.3  The  Interchangeability  designator  (last  two  digits)  indi- 
cates the  degree  of  Interchangeability  of  the  various  configurations 
of  the  routine  or  subroutine  as  follows: 

-XOl  through  -XO9  enables  identification  of  the  addition  of  a 
feature  which  is  Interchangeable  in  a program,  with  the  addition  or 
loss  of  the  feature  as  the  only  consequence  of  Interchange; 

-XIO  through  -X90  (Increments  of  10)  indicates  non- 
interchange able  items; 

-XIO  through  -XI9,  etc.  (Increments  of  1)  Indicates  inter- 
changeable Items  within  the  non -inter change able  items. 


3.1.16.4  The  revision  letter  following  the  number  indicates  a 
change  that  does  not  affect  interchangeability  nor  add  or  delete 
a feature;  l.e.,  error  correction  or  improved  approach. 
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^.1.17  Sizes 


?. 1.17.1  Each  flow  diagram  shall  be  prepared  on  a 22x56  sheet 
(maLximum),  with  the  type  or  lettering  size  suitable  for  2:1  reduc- 
tion maintaining  O.060  type  at  the  reduced  size. 

? . 1 . 18  Layout 

3.1.18.1  The  layout  for  a flow  diagram  Is  Illustrated  In  Figure  1. 

3.2  FUNCTIONAL  DESCRIPTION 

3.2.1  This  subsection  specifies  the  requirements  for  preparation 
of  Functional  Descriptions  of  Logic  Flow.  The  Functional  Descrip- 
tion is  a documentary  of  the  logic  and  logic  flow  Illustrated  by 
the  Program  Flow  Diagram.  Additionally,  It  describes  the  require- 
ment in  the  Operational  Specification  that  Is  satisfied  by  the 
portion  of  the  Flow  Diagram  being  described. 

3.2.2  Preparation 

3. 2. 2.1  One  statement  shall  be  prepared  for  each  numbered  block 
on  each  diagram.  The  statement  shall  be  a brief  description  of 
decisions  or  actions  being  performed  by  the  numbered  factional 
grouping  being  described. 

3. 2. 2. 2 For  higher  order  fiinctlonal  groupings  or  higher  order 
diagrams  (those  containing  subordinate  functional  groupings),  one 
statement  describing  the  interrelations  of  the  subfunctional  group- 
ings contained  within  the  higher  order  grouping  shall  be  provided. 

3. 2. 2. 3 Statements,  which  may  range  from  single  sentences  to 
paragraphs,  as  required,  shall  be  brief  descriptions  of  the  techni- 
cal details.  Lengthy  descriptions  are  neither  required  or  desired. 

3.2.3  Text 

3. 2. 3.1  Text  shall  be  concise.  Verbieige  is  neither  desirable  or 
permissible.  It  shall  provide  the  "what  it  does",  and  "when  it 
does",  and  "how  it  does"  description  of  each  block. 

3. 2. 3. 2 The  text  shall  be  detailed  sufficiently  to  permit  the  recon- 
struction of  the  Program  Flow  Diagram  from  the  Fxmctlonal  Description. 
The  sample  portion  of  a Fvmctlonal  Specification  corresponds  directly 
to  the  Program  Flow  Diagram  example  (Figure  1) . 
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' . . Subdivision 

' 3.2.4. 1 The  Functional  Specification  shall  be  divided  Into  chapters, 

sections,  and  paragraphs  which  are  numbered  to  correspond  with  the 
sub-functlonallzatlon  numbering  of  the  Program  Plow  Block  Diagram. 

• • Separate  chapters  shall  be  provided  for  each  of  the  major  routines 

that  make  up  the  complete  program;  l.e.,  navigation,  tracking, 

; . message  processing,  etc.  Overall  description  of  the  complete  pro- 

gram, Including  a description  of  the  Interrelations  between  the 
major  routines,  shall  be  contained  In  Chapter  0.  Each  chapter  shall 
be  divided  Into  sections,  with  one  section  provided  for  each  of  the 
major  subroutines  that  make  up  the  major  routine.  For  example,  the 
tracking  routine  chapter  would  contain  a section  for  each  of  the 
subroi'-tlnos  concerned  with  velocity  establishment,  velocity  smooth- 
■ * Ing,  remote  track  processing,  height  processing,  etc.  Overall 

[description  of  the  major  routine,  including  a description  of  the 

interrelations  of  the  subroutines,  shall  be  combined  in  Section  0. 

I 3. 2. 4. 2 The  chapter  and  section  or  division  and  numbering  technique 

I specified  provides  rapid  correlation  of  data  between  the  Functional 

Description  and  the  Program  Flow  Diagram,  and  must  be  maintained  to 
continue  this  correlation. 

[.  3. 2. 4. 3 Each  chapter  and  section  shall  begin  on  a new  page.  (It 

t,  Is  realized  that  some  sections  will  not  require  a full  page.  This 

:j  is  acceptable,  and  no  attempt  should  be  made  to  add  verbiage  simply 

2 to  fill  a page.) 

!,i  3.2.5  Rules  for  Grammar 

; ! 3. 2.5.1  Technical  accuracy  and  adequacy  are  the  prime  requisites  of 

the  f\mctlonal  description.  The  following  rules  for  grammar  are 
^ provided  In  the  Interest  of  consistency. 

i (a)  Third  person. 

(b)  Present  tense  (use  "when"  prepositional  phrase  for  time). 

(c)  Active  voice. 

, (d)  Indicative  mood. 
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3.2.6  Sximmar; 


I 


£ 

3. 2. 6.1  By  following  the  few  simple  rules  provided  in  the  preceding 
paragraphs  all  levels  of  text  will  be  covered. 

3. 2. 6. 2 The  text  describing  the  overall  program  will  define  the  I 

major  routines  involved  in  the  program,  and  describe  their  I 

Interrelationship.  I 

f 

3. 2. 6. 3 The  text  describing  each  major  routine  will  define  the  ^ 

major  subroutines  involved,  describe  the  logic  that  determines  when 

I 

the  subroutines  shall  be  employed,  and  further,  describe  the  func-  ’ 

i • 

tlon  of  each.  • 

3. 2. 6. 4 The  text  describing  each  subroutine  will  define  the  sub-  ] 

subroutines,  the  logic  that  determines  when  the  sub-subroutine  shall 

be  employed,  the  logic  used  in  each  of  the  decision  functional  , ; I 

groupings,  and  the  actions  to  be  performed  by  these  functional  | 

groupings . j 


3. 2. 6. 5  Each  statement  shall  provide  the  answers  to  the  following 
questions;  (1)  what  it  does,  (2)  when  it  does  it,  and  (3)  why  it 
does  it. 

3.2.7  Sample  Functional  Description 

3. 2. 7.1  The  following  example  is  provided  as  a guideline  for  the 
preparation  of  fvinctlonal  descriptions  of  the  various  levels  of 
functional  groupings.  Note  the  requirement  for  concise  narrative 
description  rather  than  verbiage  prose. 


3. 2. 7. 2 The  paragraphs  are  numbered  to  correspond  to  the  blocks  on 
Figure  1 and  the  text  describes  the  decisions  and  actions  that 
occur. 
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HEIGHT  PROCESSING  SUBROUTINE 


SV^  rE  HEIGHT 


13.  HEIGHT  PROCESSING 


The  Computer-detector  performs  the  height  finding  process  by- 
measuring  the  time-difference  between  the  direct  path  and  the  multi 
path  return  echo.  Results  of  the  CD  test  is  stored  in  Height 
Accumulator.  In  addition  to  the  multipath  target  feature,  other 
criteria  are  established  for  Height  Processing.  Conditions  are  pro 
vided  in  13.2  and  13.3. 

13.  1 Surface  Height 

13.1.1  Confirmed  surface  targets  (0  height)  are  processed  in  this 
grouping.  Requirements  for  confirmed  surface  targets  are  as 
follows : 

I a)  Target  within  height  finding  zone, 

b)  Target  not  locked  with  front  tag. 

c)  Target  not  locked  with  rear  tag. 

d)  No  manual  height  entered, 

e)  Valid  one  echo  report. 

f)  Surface  counter  indicates  5 valid  single  echo  returns. 

13.1.2  In  this  section  the  target  is  tested  for  position  within 
the  height  finding  zone.  The  height  finding  zone  is  defined  as 
further  than  20  mllus,  but  closer  than  200  miles.  V/hen  the  cri- 
teria is  met,  the  target  in  Height  Finding  Zone  Bit  is  set. 

13.1.3  Rules  for  counting  valid  echo  for  surface  counter  are: 

(a)  Ignore  targets  in  obscuration  zone  (front  or  rear  tag 

set ) . 

!b)  Increment  valid  echos, 
c ) Ignore  garbled  echos . 

d)  Reset  to  0 for  valid  height  (multiple  echo). 

In  this  grouping  the  front  and  rear  tag  are  tested  for  target 
location  outside  obscuration  zone,  the  surface  center  is  tested  to 
verify  that  the  surface  count  is  less  than  5,  then  the  surface 
counter  is  incremented  by  one.  Subsequently,  the  surface  counter 
is  tested  for  being  equal  to  five. 

13.1.^  In  this  section  the  surface  counter  is  tested  for  adequate 
correlation  of  valid  surface  echos  and,  provided  that  manual  height 
has  not  been  entered,  establishes  the  target  as  a surface  target 
by  setting  present  height  to  0 and  previous  height  to  maximum. 

This  ensures  a difference  between  present  height  and  previous 
height  greater  than  700  feet  thus  preventing  false  returns  from 
establishing  this  track  as  an  air  track. 
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3 . 3 PROGRAMMING  PRACTICES 


3.3.1  Rules  for  good  programming  are  helpful  for  small  programs 
coded  by  a single  programmer;  they  are  essential  for  large  programs 
coded  by  many  programmers.  The  practices  described  in  the  follow- 
ing paragraphs  are  designed  to  unify  large  programs  coded  by  many 
programmers.  Any  exceptions  to  these  rules  must  be  approved  by  a 
programming  coordinator  and  distributed  to  all  the  programmers. 
Inter-program  coding  practices  are  sufficiently  well  documented  in 
"Naval  Tactical  Data  Systenr",  Volume  2,  CS-1  Manual,  Appendix  B, 
and  will  not  be  listed  here. 

3.3.2  A variable,  assigned  a name  by  the  programmer,  can  equal 
numeric  data  or  alphanumeric  labeling  information.  Variables  may 
assume  a succession  of  values  during  execution  of  the  program. 

3. 3. 2.1  Naming  Variables.  The  data  names  of  all  variables  shall 
be  symbolic.  Variables  common  to  more  than  one  major  routine  must 
have  the  same  symbolic  name  in  all  the  routines  in  which  they 
appear.  Also,  all  data  names  shared  by  several  routines  should 
begin  with  the  same  two  letters.  The  remaining  characters  must  be 
mnemonic.  Data  names  which  appear  in  only  one  major  routine  shall 
all  begin  with  two  letters  uniquely  assigned  to  that  routine.  For 
example,  a variable  used  only  in  the  executive  module  might  be 
named  EXRTF,  where  EX  stands  for  Executive  module  and  RTF  is  Real 
Time  Flag.  Similarly  TKRTD  is  the  Real  Time  Decode  from  the 
Tracking  Routine.  All  variables  used  only  by  the  Executive  Routine 
should  begin  with  EX,  and  all  those  used  only  by  the  Tracking 
Routine  should  begin  with  TK.  Appendix  R of  the  CS-1  Programmers 
Guide,  contains  a "Restricted  Word  List";  data  names  should  not  be 
any  of  the  words  on  this  list. 

3. 3. 2. 2 Definition  of  Variables  Assigned  as  Data  Units.  All  data 
units  common  to  a routine  shall  be  defined  at  the  beginning  of  the 
source  program.  Data  names  defining  tables  shall  be  grouped 
together,  as  shall  data  names  defining  variables,  indices,  titles, 
and  switches. 
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-s. 1 In  codint'  programs  which  require  a great  deal  of  core,  | 

r.omo  programmers  may  try  to  reduce  core  use  by  sharing  scratch  I 

storage  between  routines.  This  is  accomplished  by  transferring  a I 

scratch  storage  data  unit  to  a second  program  as  an  input  parameter  ] 

so  tlie  second  program  can  share  the  first  program's  scratch  storage.  ) 

This  practice  can  be  a source  of  many  errors  and  should  be  avoided  | 

wlu'ni^ver  possible.  I 

i 

I 

3.0.3  Operations  define  the  action  the  program  is  to  take  for  one 
instruction. 


3. 3. 3.1  Operation  Procedures.  It  is  necessary  to  provide  rules  to 
insure  uniform  coding  by  different  programmers.  Since  programmers 
wl.il  have  different  coding  styles  (and  specialties),  more  rigid 
regimentation  of  coding  practices  will  be  necessary  in  this  section 
than  at  any  other  level.  Further,  uniform  coding  will  help  insure 
that  an  optimal  method  of  coding  is  employed,  since  coding  which  is 
used  repeatedly  should  encourage  a higher  level  of  effort  by  the 
;|  programmer.  The  resulting  coding  can  be  of  two  types: 

3. 3. 3.?  Brief  Groups  of  Coding.  Some  judgment  must  be  exercised 
before  deciding  that  a given  collection  of  instructions  is  used 
often  enough  to  be  made  into  a procedure.  It  may  save  machine-run 
time  to  simply  repeat  the  collection  of  instructions  at  each  use, 
rather  than  to  call  a procedure  which  performs  the  functions  of  the 
instructions.  Coding  of  a collection  of  instructions  should  be 
reviewed  by  a systems  analyst  for  optimal  coding.  Its  subsequent 
use  throughout  all  the  routines  must  be  as  uniform  as  possible. 

Konstandard  use  of  poly  operations  in  such  coding  should  be  avoided, 
since  mono  operations  will  provide  more  efficient  coding  in  these 
cases.  These  collections  of  instructions  should  be  given  names  or 
be  labeled  (by  comment  cards)  so  they  may  be  referenced.  I 

I 

3. 3. 3. 3 Procedures . Those  groups  of  instructions  which  are  « 


repeated  frequently  and  which  are  long  enough  to  justify  the  time 
consumed  by  linking  instructions  should  be  written  in  procedure 


storage  needed  for  a procedure  must  be  specifically  assigned.  The 
arbitrary  unique  names  assigned  to  input,  output,  or  exit  param- 
eters in  defining  a procedure  should  be  mnemonic.  If  the  number  of 
input,  output  and  exit  parameters  exceeds  the  limit  of  the  compiling 
system  in  use,  the  usual  technique  to  bypass  this  restriction  Is  to 
pack  several  variables  into  a newly  defined  data  unit  and  then  use 
the  new  data  unit  as  a parameter  to  the  procedure.  This  should  be 
avoided  if  possible,  but  if  it  is  the  only  solution  to  the  prob- 
lems caused  by  this  restriction,  then  the  newly  defined  data  unit 
must  not  be  used  for  any  other  purpose  and  must  be  documented  by 
comment  cards  (see  3*^).  All  procedures  must  be  docximented  by 
comment  cards  for  subfunctional  routines  as  defined  in  3.4,  where 
they  apply  to  the  procedure.  Finally,  abnormal  exits  should  be 
grouped  at  the  end  of  the  procedure  and  should  not  Interrupt  the 
normal  flow  of  the  procedure. 

3.3.4  Diagnostic  Output 

3. 3.4.1  Errors  during  execution  can  be  of  two  kinds: 

(a)  Machine  errors  — Since  machine  errors  rarely  occur  on 
equipment  which  Is  tested  dally,  the  program  need  only  test  for 
human  error. 

(b)  Human  error  — Input  to  the  programs  will  be  provided  in 
part  by  operators  of  the  equipment.  The  programs  will  test  that  all 
such  input  is  within  the  range  of  acceptable  data.  When  Incorrect 
data  is  fo;and,  the  program  must  output  a diagnostic  message. 
Incorrect  input  and  the  errors  it  produces  are  called  error 
conditions . 

3. 3. 4. 2 Those  error  conditions  which  are  common  to  more  than  one 
routine  shall  have  a uniform  diagnostic  message  which  gives  the 
error,  the  state  of  the  computer  registers  (if  appropriate),  the 
absolute  location  where  the  error  occurred,  and  the  name  of  the 
routine  in  which  the  error  occurred.  In  order  to  avoid  sharing 
duplicate  output  statements  in  several  routines,  an  error  procedure 
shall  be  supplied.  Such  a procedure  would  be  called  by  the 
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routines  when  an  error  condition  is  encountered.  One  of  the 
arguments  used  to  enter  the  error  procedure  would  Indicate  the  type 
of  error  encountered. 

3. 3.^.3  Those  errors  not  common  to  several  routines  should  follow 
the  general  print  format  of  the  error  procedure,  but  they  may  be  a 
part  of  the  routine  where  they  occur,  rather  than  being  a part  of 
the  error  procedure.  They  should  be  placed  at  the  end  of  the  rou- 
tine so  they  will  not  Interrupt  the  flow  of  the  program  for  a 
normal  run. 

3.3.5  Linking,  Branching,  and  Overwriting 

3. 3. 5.1  The  contents  of  the  index  registers,  location  coiinter, 
arithmetic  registers,  sense  switches,  and  overflow,  underflow,  and 
divide  check  sensors  all  reflect  the  state  of  the  computer  at  exe- 
cution time.  When  linking  procedures,  some  of  these  must  remain 
unchanged.  Uniform  coding  practices  demand  that  the  programmers 
agree  on  a list  of  those  registers  and  counters  which  must  be  pro- 
tected within  a procedure.  Then  the  contents  of  the  registers  and 
counters  which  are  to  be  protected  are  saved  at  the  entry  point  to 
the  procedure  and  are  restored  at  the  exit  points  of  the  procedure. 

3. 3. 5. 2 A procedure  may  not  change  an  instruction  in  a routine. 

If  it  is  necessary  to  overwrite  a particular  instruction  word  in 
another  routine  at  execution  time,  the  flow  of  the  program  must 
transfer  to  the  routine  to  be  overwritten.  Thus,  the  instructions 
causing  the  overwriting  will  be  executed  in  the  routine  to  be  over- 
written. Even  so,  all  such  overwriting  must  be  properly  documented 
by  Comment  Cards  and  should  be  avoided  whenever  possible. 

3. 3. 5. 3 The  main  flow  of  the  program  should  proceed  down  the  page 
(of  the  listing)  or  sequentially  through  core  storage.  Major 
branches  will  be  at  the  end  of  the  program.  In  general,  the  flow  of 
the  program  should  reflect  as  closely  as  possible  the  direction  of 
the  flow  chart. 

3.3.5.^  Instructions  to  which  the  program  flow  is  transferred  must 
have  a label.  This  label  should  be  assigned  a symbolic  name; 
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absolute  locations  should  be  avoided.  In  particular,  no  subprogram 
should  refer  to  a branch  point  as  "N  operations  from  this  one"  as 
in  FAP  we  might  write  "TRA  A + 4",  meaning  transfer  to  four  loca- 
tions after  symbolic  location  A. 

3. 3. 5. 5 The  symbolic  labels  for  transfer  points  can  be  a debugging 
aid.  The  symbolic  label  should  reflect  the  particular  step  in  the 
program  where  the  operation  is  performed.  It  would  be  particularly 
helpful  if  the  label  referred  to  the  nvmiberlng  system  of  the  Plow 
Charts . 

3.4  COMMENT  CARDS  AND  PLOW  CHART  CARDS 

3.4.1  Definition 

3.4. 1.1  Comment  Cards . The  CS-1  Compiler  allows  the  programmer 

to  insert  coding  explanations  in  the  body  of  a program  by  an  opera- 
tor called  "Comment."  This  comment  is  printed  in  the  listing  in 
the  same  position  with  respect  to  the  coding  as  it  had  in  the  source 
deck. 

3.4. 1.2  Plow  Chart  Cards.  The  CS-1  Compiler  allows  the  programmer 
to  insert  PC  Cards  in  the  body  of  the  program.  At  compile  time, 
these  cards  are  printed  with  the  listing  as  were  the  Comment  cards, 
and  they  also  can  be  printed  as  a special  output  from  the  listing 
in  the  form  of  a flow  chart.  In  addition.  Plow  Chart  Comment  Cards 
("PC  Comment")  will  cause  the  compiler  to  print  the  PC  Comment 
information  in  the  body  of  the  listing  and  also  print  the  informa- 
tion to  the  extreme  right  of  the  page  containing  the  flow  charts 
for  that  section  of  coding. 

3.4.2  Use 

3. 4. 2.1  Comment  and  Plow  Chart  Cards  are  Inserted  within  a source 
program  deck  as  an  aid  in  all  aspects  of  maintenance,  reliability, 
and  revisabllity  of  the  source  program.  Since  the  comments  on  the 
cards  are  an  Integral  part  of  the  source  program  listing,  they  are 
the  form  of  documentation  most  readily  available  to  the  pro- 
grammer. Revisions  of  the  source  program  will  require  revisions  of 
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associated  Comment  and  Plow  Chart  Cards  when  a discrepancy  exists 
between  the  changed  program  and  the  original  Comment  Cards. 

3.H.2.2  Comment  and  Plow  Chart  Cards  are  to  be  prepared  so  that 
when  printed  by  the  compiler,  there  will  be  no  midword  break  unless 
it  is  a syllable  break  at  the  end  of  the  line,  with  the  conventional 
hyphen  (-)  to  indicate  this.  Also,  comments  should  be  in  complete 
sentences  when  they  are  describing  an  operation  or  sequence  of 
operations.  Only  labeling  descriptions  may  be  written  in  phrases. 

3.4.3  Required  Content 

3.4.3. 1 There  are  four  kinds  of  Comment  and  Plow  Chart  Cards, 
catalogued  by  their  position  in  the  source  program:  (1)  lead  cards 
(2)  subfunctional  lead  cards  (3)  Internal  comment  cards,  and 

(4)  final  comment  cards.  Each  of  the  card  types  is  described 
subsequently. 

3. 4. 3. 2 Lead  Cards.  Lead  cards  precede  the  program  cards  for  each 
major  routine  of  the  program,  and  precede  the  cards  for  the  complete 
program.  The  information  required  on  the  lead  cards  is  identical 
for  either  use.  Lead  cards  shall  be  of  three  types:  (a)  purpose 
definition  cards  (b)  operating  Instruction  cards,  and  (c)  data  unit 
description  cards. 

3. 4. 3. 2.1  Purpose  Definition  Cards.  Purpose  definition  cards  pro- 
vide the  following  information: 

(a)  A brief  description  of  the  function  of  the  program  (written 
as  a Plow  Chart  Comment  Card). 

(b)  A breakdown  of  the  function  of  the  program  into  subfunc- 
tions. This  should  be  of  the  form:  number,  title,  description  of 
subfunction.  "Number”  must  be  the  configuration  control  number  and 
"title"  must  correspond  to  the  title  of  that  subfunction  as  listed 
in  the  functional  specifications.  The  description  may  correspond  to 
the  functional  specifications  description,  since  it  need  serve  only 
to  distinguish  one  subfunction  from  another  (written  as  a Comment 
Card) . 
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3. ^.3. 2. 2 Operating  Instruction  Cards.  (Written  as  Comment  Cards. 
Operating  Instruction  cards  provide  the  following  Information: 

(a)  Input  and  output  requirements.  Since  the  details  of 
these  requirements  appear  In  the  documentation  for  the  Testing 
Routine  for  this  program,  this  description  need  not  be  detailed  or 
referenced,  but  must  be  complete  enough  to  supplement  the  purpose 
definition  (see  3.4. 3.2.1  (b))  In  an  understanding  of  the  program. 
The  source  of  the  Input  and  the  destination  of  the  output  should  be 
given. 

(b)  Auxiliary  equipment  needed.  If  special  tapes,  punched 
tape,  cards,  or  cathode  ray  tube  displays  are  needed  by  the  program 
for  Input  or  output,  the  Comment  Cards  should  list  the  equipment 
type  and  model  number  as  well  as  give  a unit  designation  when  the 
executive  system  requires  it. 

(c)  Sense  switches  or  console  switches  which  must  be  set  at 
the  beginning  of  the  program  or  at  Intermediate  points  during  exe- 
cution of  the  program. 

(d)  List  of  operator  action  to  interrupt  the  program  because 
of  error  diagnostics.  It  Is  suggested  that  the  Comment  Cards  list 
the  type  of  error,  the  action  to  be  taken,  and  the  subfunctlonal 
program  number  (or  numbers)  that  can  give  this  error. 

(e)  Subroutines,  Identified  by  version  n\ambers,  which  are 
not  part  of  the  subprogram  breakdown  or  the  system  executive  rou- 
tine but  which  are  used  by  the  program  and  must  be  loaded  with  the 
program  In  order  that  the  program  will  run. 

(f)  Core  storage  requirements  for  this  routine  and  those 
subroutines  in  (e)  above. 

3. 4. 3. 2. 3 Data  Unit  Description  Cards.  All  that  data  referenced 
by  several  subfunctlonal  procedures  throughout  the  program  will  be 
part  of  the  syr  tern  data  design.  Each  table  defined  must  be  pre- 
ceded by  a Comment  Card  giving  the  fxinctlonal  description  of  the 
table  In  the  program.  Any  nonstandard  use  of  tables  or  their 
associated  Indices  should  be  documented  here.  Single  word  vari- 
ables should  also  be  described  here  by  Comment  Cards. 


3.^. 3* 3 Subfunctlonal  Lead  Cards.  Subfunctlonal  lead  cards  precede 
and  describe  the  subroutines  within  the  major  routine  illustrated 
by  tb#»  individual  Logic  Plow  Block  Diagrams.  Subfunctlonal  lead 
cards  shall  be  of  three  types:  (a)  purpose  definition  cards 

(b)  operating  instruction  cards,  and  (c)  data  unit  description  cards. 

3.4. 3. 3.1  Purpose  Definition  Cards.  Purpose  definition  cards  shall 
contain  the  following  information. 

(a)  Description  of  the  function  of  this  subprogram  in  complete 
sentences  (Flow  Chart  Comment  Card). 

(b)  List  of  algorithms  or  techniques  used  to  achieve  the 
purpose  of  this  subprogram.  Error  formulas  on  numeric  alogrlthms 
should  be  given  (Comment  Card). 

(c)  Details  of  input  requirements  with  an  example,  if  possible 
(Comment  Card). 

(d)  List  of  the  steps  taken  in  this  subprogram  to  test  the 
input  data  and  achieve  the  function  of  the  subprogram.  The  step 
numbers  must  correspond  to  the  sub -subfunctlonal  breakdown  appearing 
on  the  flow  charts  (Comment  Card). 

(e)  Author  of  the  original  subprogram  and  responsible  pro- 
grammer of  this  revision  (Comment  Card). 

(f)  Piling  number  of  the  testing  routine.  Date  of  last  test 
of  this  subprogram  with  its  testing  routine  (Comment  Card). 

(g)  List  of  the  manuals,  books,  articles,  etc.,  which  may  be 
of  use  in  duplicating  this  function  on  another  computer  in  another 
language.  The  Functional  Specifications  and  Operational  Specifi- 
cations are  considered  source  material  and  need  not  appear  in  this 
bibliography.  (Comment  Card.) 

3 .4. 3. 3. 2 Operating  Instruction  Cards.  Operating  Instruction 
cards  shall  contain  the  following  information  (all  are  Comment 
Cards ) : 

(a)  A Testing  Boutlne  description  which  describes  the 
generation  of  data  in  the  subroutines  and  gives  enough  information 
about  the  testing  routine  to  delineate  the  parts  of  the  subprogram 
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that  it  tested.  Sample  input  and  output  examples  may  be  given  to 
help  clarify  the  functions  of  the  subprogram.  These  examples  may 
be  taken  from  the  examples  used  to  document  the  Testing  Routine  for 
this  subprogram. 

(b)  A list  of  auxiliary  equipment  required  by  this  subprogram, 
with  the  type,  model  number,  and  unit  designation,  if  required.  If 
manual  page  references  for  this  equipment  would  be  helpful  in  rim- 
nlng  the  program,  the  manual  name  and  edition  should  also  be  given. 

(c)  A list  of  sense  switches  which  must  be  set  by  the  operator 
at  the  beginning  of  the  program  or  at  an  intermediate  point  during 
execution,  along  with  their  settings. 

(d)  A list  of  error  possibilities  which  require  operator 
intervention.  Further,  if  some  errors  cause  termination  of  the  run, 
these  errors  should  also  be  listed  here.  The  information  required 
in  the  Comment  Cards  is ; 

(1)  Type  of  error,  its  display  or  diagnostic 
characteristics, 

(2)  Possible  locations  in  the  subprogram, 

(3)  Operator  (or  programmer)  intervention  to  bypass  or 
correct  this  error. 

3-^-3-3*3  Data  Unit  Description  Cards.  Local  data  design  units 
must  be  documented  by  preceding  each  definition  with  comment  cards 
which  adequately  describe  the  data’s  function  in  the  subfunctional 
program. 

3.4. 3.4  Internal  Comment  and  Flow  Chart  Cards.  Internal  Comment 
Cards  describe  the  coding  techniques  used  in  coding  a particular 
step  in  a subfunctional  program  grouping  within  a subroutine.  They 
are  mainly  a debugging  aid. 

3. 4. 3. 4.1  Flow  Chart  Cards  specify  the  programming  and  algebraic 
steps  taken  to  achieve  the  subf^inctlonal  result  required.  Plow 
Chart  Comment  Cards  describe  in  engineering  English  the  program- 
ming steps  documented  by  the  Plow  Chart  Cards.  The  number  of  the 
fvinctlonal  grouping  on  the  logic  flow  block  diagram  which  contains 
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the  logic  being  coded  by  these  Instructions  or  steps  should  appear 
on  the  first  flow  chart  card  of  such  a functional  grouping. 

3.^. 3.^.2  Internal  comment  cards  provide  the  following  information 
for  each  step  in  the  coding. 

(a)  The  card  numbers  of  any  transfer  points  which  transfer 
into  the  beginning  of  this  step. 

(b)  List  of  maximum  and  minimum  time  estimates  in  machine 
cycles  if  the  program  is  for  a real  time  problem. 

(c)  If  Brief  Groups  of  Coding  (see  3. 3- 3. 2)  are  used,  the 
name  of  the  block  of  coding  and  its  author  should  be  referenced. 

(d)  Any  use  of  packed  data,  linked  lists,  or  second-level 
indexing  must  be  referenced  by  an  example.  The  bit  configuration 
of  packed  data  must  be  given.  This  need  only  be  done  before  the 
first  use  of  the  word,  list,  or  array  in  any  subfunction.  Its  use 
in  subsequent  steps  must  be  referenced  to  point  back  to  its  first 
use. 

(e)  The  card  number  of  any  instruction  written  on  by  this 
Instruction. 

(f)  Any  instruction  which  is  written  on  at  execution  time 
must  be  accompanied  by  a comment  card  giving  the  card  number (s)  of 
the  instruction (s ) which  wrote  on  it. 

(g)  All  steps  in  coding  which  would  not  be  understood  by  a 
programmer  with  three  months ' coding  experience  must  be  explained 
by  comment  cards. 

3.4. 3*^. 3 Flow  Chart  Cards  will  bear  a one  to  one  correspondence 
to  the  blocks  of  the  Functional  Flow  Chart  as  described  in  3. 1.5.4. 
Thus,  before  each  block  of  programming  which  performs  a sub- 
subfunction as  Indicated  by  one  block  of  the  Functional  Flow  Chart 
for  this  subfunction,  the  programmer  must  place  an  algebraic  or 
programming  oriented  description  of  the  step  to  be  done.  Symbolic 
names  are  to  be  used,  and  a uniform  assignment  of  verbs  to  corre- 
spond to  the  Flow  Chart  symbols  used  within  the  block  will  make 
these  Flow  Chart  Cards  more  understandable. 
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3.^.3.^*^  Plow  Chart  Comment  Cards  will  precede  the  Flow  Chart 
Cards  for  a sub-subfunctlonal  block  of  programming  and  will  corre- 
spond exactly  to  the  Program  Plow  Diagram  entry  for  this  block  of 
programming. 

3 . ^ . 3 . 5 Final  Comment  Cards 

3. ^.3* 5.1  Indexes.  If  the  compiler  used  does  not  produce  the 
indexes  listed  as  "required"  under  3.6  (program  assembly  listings), 
then  the  final  comment  cards  must  reproduce  these  indexes. 

3. ^(■.3.5.2  Groups  of  operations  which  were  repeated  more  than  once 
in  the  routine  should  be  given  a name,  described,  and  a list  of  the 
sections  of  the  routine  where  they  were  used  should  be  given.  The 
author  and  the  senior  analyst  who  checked  the  coding  should  be 
given  for  each  such  group. 

3.^.3.5*3  Suggested  Revision  Digest.  Because  of  the  dynamic  nature 
of  military  tactical  situations,  revisions  are  anticipated.  As 
such,  a repository  for  potential  areas  of  program  Improvement  is 
provided.  All  suggestions  in  these  cards  will  be  reviewed  by  PCPC 
for  possible  incorporation  concurrent  with  the  subsequent  revision. 
Each  suggestion  must  contain  the  name  of  the  programmer  suggesting 
the  revision;  date  the  Comment  Card  was  written;  part  of  the  pro- 
gram (by  Flow  Chart  number)  the  suggestion  pertains  to;  the  sug- 
gestion; and  concurring  programmers. 

NOTE 

Where  Testliig  Routine  Comment  Cards  differ  from 
the  above  Comment  Cards,  they  will  be  described 
in  the  section  on  testing  routines. 

3.5  PROGRAM  CARD  DECK 

3.5.1  The  program  card  deck  is  the  collection  of  IBM  cards  on 
which  the  source  language  coding  and  comment  cards  have  been  key- 
punched. All  cards  shall  be  interpreted  in  a plain-language  charac- 
ter set.  One  program  card  deck  shall  be  prepared  for  each 
program. 


3-32 


3.5.2  Color  and  Spacing 


3.5.2. 1 Program  cards  shall  he  white  with  cut  corners.  Spacing 
will  be  consistent  with  compiler  language  requirements.  Comment 
cards  shall  be  buff  with  square-cut  corners.  Header  cards  should 
be  bright  colored  or  have  a bright,  contrasting  top  edge. 

3.5.3  Type 

3. 5.3*1  Cards  shall  be  standard  80-column  IBM  cards. 

3.5.^  Summary 

3. 5. 4.1  The  use  of  color  is  limited  to  that  which  will  serve  a 
functional  purpose,  such  as  enabling  PCPC  personnel  to  locate 
rapidly  the  cards  associated  with  routines  and  subroutines  within 
the  deck. 

3.6  PROGRAM  COMPILATION  LISTING 

3.6.1  A program  compilation  listing  is  a computer  generated 
listing  of  the  compiled  source  program  with  its  comment  cards  and 
its  translation  into  the  object  program  in  core  memory.  In  addi- 
tion, some  compilers  provide  symbolic  reference  tables,  literal 
reference  tables,  etc.  The  following  lists  should  either  be  com- 
pilation output  or  if  the  compiler  will  not  provide  them,  final 
comment  cards  (see  3. 4. 3.5). 

3.6.2  Date  of  Compilation 

3. 6. 2.1  An  alphabetized  list  of  all  the  labels  used  in  the  program, 
their  assigned  core  location  and  the  core  locations  which  refer  to 
them. 

3. 6. 2. 2 A list  of  all  the  labels  used  in  the  program  arranged  in 
Increasing  order  of  their  core  location  assignment,  or  a list  of 
the  labels  and  their  compiler  generated  or  sequence  number  arranged 
in  card  sequence  number  order. 
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3. 6. 2. 3 A list  of  variable  names  (or  table  and  field  names)  ■ | 

arranged  in  alphabetic  order  with  their  use  referenced  by  core  loca- 
tion or  sequence  number.  ^ 

3. 6. 2. 4 A list  of  index  register  usage  should  be  supplied.  Ideally, 
this  should  provide  the  index,  the  index  name  used,  the  procedure 

it  was  used  in  and  the  memory  locations  which  referred  to  it. 

I , 

j 

3. 6. 2. 5 A separate  list  for  each  procedure  should  give  the  number 

of  Inputs,  outputs  and  abnormal  exits  for  each  procedure;  it  should  ‘ ■ 

also  list  the  other  procedures  used  by  this  procedure  and  the  pro-  ' 

cedures  which  use  this  procedure.  Any  special  switches,  indices,  ) 

labels  or  variables  used  by  the  procedure  should  appear  in  this  -> 

report.  The  amount  of  memory  occupied  by  the  procedure  should  be  . 

given  too.  , i , 

3.7  TESTING  ROUTINE  j 

3.7.1  A testing  routine  is  a computer  program  which  tests  another 

computer  program.  It  reads  in  or  generates  input  data,  calls  the  | 

program  to  be  tested  (as  a subprogram),  and  analyzes  the  output 

from  the  tested  program.  The  testing  routine  output  consists  of  ' : 

timing  Information,  storage  use,  and  any  programming  errors  dis- 
covered in  the  tested  program. 

3.7.2  Requirements 

3.7.2. 1 The  programmer  of  a testing  routine  shall  code  the  testing 
routine  from  the  Operational  Specifications  and  the  Program  Flow  I 

Diagram  of  the  program  to  be  tested.  If  the  Operational  Specif ica-  j 

tlons  place  limits  on  the  timing  and  the  amount  of  data  which  the 
tested  program  must  process,  then  the  testing  routine  will  exercise  ! 

the  tested  program  to  these  limits.  A testing  routine  shall  not  be 
written  by  the  programmer  of  the  tested  program.  Testing  routines  ^ 

are  considered  to  be  a deliverable  program  routine;  therefore,  all 
requirements  for  Program  Flow  Diagrams,  Functional  Descriptions,  j 

Functional  Specifications,  Functional  Flow  Charts,  program  card  deck 
and  source  program  listings  shall  apply  to  Testing  Routines.  || 


3. 7. 2. 2 Testing  Routines  are  divided  into  two  types: 

(a)  Those  which  test  each  branch  point  possible  within  a 
program  and  which  test  the  program  for  extreme  cases  of  storage  use 
and  timing  limits. 

(b)  Those  which  supply  simulated  data  which  represent  the 

ordinary  use  of  the  tested  program.  This  type  of  testing  routine 

( 

gives  timing  and  use  statistics  which  reflect  its  use  when  the 
tested  program  is  operational. 

3. 7. 2. 3 The  first  type  of  testing  routine  shall  be  called  a 
"Logical  Routine",  the  second  type  shall  be  called  a "Simulation 
Routine".  They  are  described  in  detail  in  3«7.3  and  3.7.^.  Com- 
ment Cards  for  both  types  of  testing  routines  are  described  in 
3.7. 1.3.  If  the  system  for  which  the  programs  were  written  have  a 
module  test  tool  which  will  check  the  timing  of  modules  in  the  total 
program,  then  the  module  test  tool  may  be  a part  of  the  Simulation 
Routine  and  the  Logical  Testing  Routine. 

3.7.3  Logical  Testing  Routine 

3. 7. 3.1  Data  Design.  The  Logical  Testing  Routine  programmer  shall 
design  input  data  for  the  testing  routine  which  cause  the  flow  of 
the  program,  during  execution,  to  enter  every  possible  combination 
of  paths  and  to  evaluate  the  limits  set  by  the  Operational  Specifi- 
cations. Thus,  if  it  is  possible  for  the  flow  of  the  program  to 
enter  branch  B after  branch  C,  one  set  of  data  read  by  the  testing 
routine  will  cause  this  sequence  of  branches  to  be  executed.  Fur- 
ther, if  the  Operational  Specification  requires,  for  example,  that 
up  to  100  tracks  be  processed  at  one  time,  then  one  set  of  data 
read  by  the  testing  routine  will  assume  that  100  tracks  are  proc- 
essed by  the  tested  program. 

3. 7. 3. 2 Data  Output.  Output  will  consist  of  a description  of  the 
combinations  of  branches  taken,  the  timing  required  to  execute  each 
of  these  combinations  of  branches,  the  output  resulting  from  each 
of  these  executions  (a  core  display  is  not  necessary,  only  a print- 

L out  or  display  of  the  values  of  those  variables  which  would  be  input 
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to  a subsequent  program  or  cause  further  branching  to  a subsequent 
program),  any  error  conditions  encountered,  and  the  absolute  core 
location  where  they  were  encountered. 

3 • 7 . 3 • 3 Logical  Testing  Routine  for  Executive  Control  Routine.  The 
Logical  Testing  Routine  for  an  Executive  Control  Routine  (which 
integrates  the  operations  of  several  programs)  should  be  capable  of 
calling  for  all  logically  possible  combinations  of  these  programs. 
It  will  thus  have  the  ability  of  calling  for  specific  combinations 
of  programs  with  data  designed  to  exercise  the  programs  according 
to  Logical  Testing  Routine  requirements. 

3.7. ^  Simulation  Testing  Routines 

3.7. ^. 1 Inputs.  Inputs  shall  be  as  statistically  close  to  Input 
data  of  real  performance  as  possible.  If  it  is  feasible,  the  aux- 
iliary equipment  which  supplies  the  input  data  in  the  "real  world" 
use  of  the  program  should  be  used  to  generate  input  data.  If 
government  prepared  data  is  available  which  meets  the  requirements 
of  the  Operational  Specifications,  it  should  be  used  as  at  least 
part  of  the  input  data  for  the  Simulation  Testing  Routines.  Since 
the  results  of  Simulation  Testing  Routine  runs  will  be  used  to 
evaluate  the  effectiveness  of  the  tested  program,  data  as  similar 
to  real  data  as  possible  should  be  prepared.  It  may  be  possible, 
in  systems  programming  (where  many  small  programs  fit  together  to 
form  a system),  to  use  the  output  from  a Simulation  Routine  run  of 
one  program  as  input  to  another  program  within  the  system  (for 
amplification  see  3.7 3) • 

3. 7.  ^.2  Outputs . Output  will  be  divided  into  five  types; 

(a)  A statistical  evaluation  of  the  input  data  and  a break- 
down as  to  the  types  of  input  entering  the  program. 

(b)  Total  program  processing  time  for  a given  sample  of  the 
input  data  and  the  percentage  of  use  the  different  steps  (in  the 
subfunctional  breakdown  of  the  program)  of  the  program  received  for 
a given  sample  of  the  data. 

(c)  A statistical  evaluation  of  the  output  from  the  program. 


(d)  Error  diagnostics  auid  the  conditions  under  which  they 
occurred.  Including  a sample  of  the  data  inducing  the  error. 

(e)  Storage  usage  during  execution  (consisting  of  the  maximum 
amount  of  storage  use  for  different  tables,  the  least  amount  of 
storage  used,  and  the  average  used),  sampled  over  a wide  enough 
range  of  times  to  provide  valid  information. 

3 . 7 . ^ . 3 Simulation  Testing  Routines  for  Executive  Control  Routines. 
A Simulation  Testing  Routine  for  an  Executive  Control  Routine  should 
be  capable  of  displaying  the  Integration  of  all  logically  possible 
subprograms  within  the  system.  The  requirements  under  3.7.4. 1 and 

3. 7. 4. 2  shall  hold  for  this  testing  routine.  In  addition,  frequency 
of  use  figures  for  each  of  the  programs  (as  in  the  steps  of  the  sub- 
functional breakdown  in  3 *7 .4. 2 (b))  should  be  part  of  the  output. 

It  should  be  possible  to  select  the  sequence  of  combinations  of  pro- 
grams as  part  of  this  testing  routine. 

3.7.5  Comment  Cards  for  Testing  Routines 

3. 7. 5.1  The  Comment  Cards  of  a testing  routine  differ  somewhat  from 
the  Comment  Cards  for  a program  as  described  in  Section  3.4. 

3. 7.5.2  Lead  cards  precede  any  instructions  in  the  testing  routine. 
They  consist  of  the  two  types  listed  in  3. 4. 3. 2.  They  need  only 
give  the  following: 

(a)  Which  of  the  two  types  of  testing  routine  this  program  is, 
and  the  name  of  the  tested  program  with  its  configuration  control 
number. 

(b)  The  major  steps  within  the  testing  routine  need  not  con- 
form to  configuration  control  step  numbers  for  the  tested  program. 
The  identification  of  the  testing  routine  is  deemed  sufficient. 

3. 7. 5. 3 Operating  instructions  in  the  lead  cards  will  be  more 
specific  than  the  program  comment  cards  on  input  and  output. 

(a)  Input  and  output  requirements  should  be  Illustrated  in 
the  Comment  Cards  by  examples  of  the  bit  configuration  (where  packed 
words  are  input)  the  quantities  to  be  expected,  and  the  limits  in 


size  of  individual  nxunbers  (where  full  words  are  input).  Expected 
output  should  he  similarly  Illustrated.  The  kind  of  equipment  sup- 
plying this  data  should  be  given  here.  This  is  not  avixiliary 
equipment,  but  rather  it  is  the  source  of  the  input.  For  example, 
if  magnetic  tapes  supply  the  input,  the  density  of  the  tape,  the 
type  of  unit  which  generated  the  tape,  whether  the  tape  is  in  the 
binary  or  BCD  mode  should  all  be  given  in  the  Comment  Cards.  If 
the  testing  routine  requires  special  system  data  cards,  these  cards 
and  their  function  shall  be  described  in  the  lead  comment  cards. 

The  remainder  of  the  operating  instructions.  Comment  Cards  (b) 
through  (e),  hold  as  described  in  3. ^.3. 3. 2. 

3.7.5.^  Sub functional  Lead  Cards.  Subfunctional  lead  cards  for 
testing  routines  are  rarely  relevant,  since  most  testing  routines 
are  quite  short  and  depend  on  their  data,  whether  read  in  or  gene- 
rated, to  exercise  the  tested  program. 

3. 7. 5. 5 Internal  Comment  Cards.  Internal  comment  cards  (3.4. 3.4) 
hold  for  testing  routines  where  the  coding  is  sufficiently  sophisti- 
cated to  merit  them.  It  is  not  expected  that  as  much  debugging  and 
revision  of  testing  routines  will  be  needed  as  compared  with  the 
tested  program,  so  Internal  comment  cards  will  not  be  as  necessary 

^1  for  the  maintenance  of  the  testing  routine.  Plow  Chart  Cards  and 

j Plow  Chart  Comment  Cards  will  reflect  the  Functional  Plow  Chart 

I blocks  and  Program  Plow  Diagram  blocks,  respectively. 

3. 7. 5. 6 Final  Comment  Cards.  Final  comment  cards  may  be  deleted 
for  testing  routines. 

3.8  FORMAT 

3.8.1  The  following  paragraphs  define  the  format  to  be  used  for 

i j the  preparation  of  each  of  the  deliverable  end  items  required  by 

the  specification. 

3.8.2  Program  Flow  Diagrams 

3.8.2. 1 Original  art  shall  be  prepared  on  a translucent  material 
! such  as  vellum,  with  1/8"  dropout  blue  quadrille  markings.  The 
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material  shall  be  selected  to  be  compatible  with  ozalid  or  equal 
process.  Image  area  shall  be  20"  high  by  length  as  required,  but 
not  to  exceed  5^".  The  image  area  has  been  established  to  be  com- 
patible with  2:1  reduction  for  final  production. 

3. 8. 2. 2 Lettering.  Lettering  typewritten  on  translucent  friskit 
and  affixed  to  the  diagram  is  preferred.  Since  this  technique  has 
not  been  accepted  as  an  industry  standard,  legible  hand  lettering 
is  acceptable. 

3. 8. 2. 3 Inking.  Line  art  shall  be  inked  according  to  the 
following  line  weight  list. 

Action  or  Decision  Boxes  Leroy  No.  3 or  equal 

Program  Plow  Lines  Leroy  No.  5 or  equal 

Grouping  Lines  Leroy  No.  1 or  equal 

Major  routines  shall  be  enclosed  by  a solid  line.  Subordinate 

routines  within  the  major  routine  shall  be  enclosed  by  a dashed  line 
with  1/2"  dashes  with  1/4"  spacing.  The  second  level  of  subordi- 
nation within  the  major  routine  shall  be  enclosed  by  dashed  line 
with  1/4"  dashes  with  1/8"  spacing.  The  third  level  of  subordina- 
tion within  the  major  routine  shall  be  enclosed  by  dashed  lines 
with  1/8"  dashes  with  1/8"  spacing.  The  engineering  data  block 
shall  be  located  in  the  lower  right-hand  corner,  inside  the  image 
area. 

3. 8. 2. 4 Titles.  Drawing  titles  shall  be  located  in  the  bottom 
margin  outside  the  image  area  such  that  they  end  flush  right  with 
the  image  area.  Figure  numbers  are  not  required.  The  engineering 
data  block  and  the  prime  number  identifier  at  the  functional  block 
provides  adequate  identification. 

3. 8. 2. 5 Review  Copies.  Review  copies  shall  be  ozalid  process  or 
equivalent  reproductions  of  the  original  art.  Because  of  the  short 
life  span  of  the  review  diagram,  low  cost  is  the  prime  criterion. 
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3.8.3  Functional  Descriptions  of  Logic  Flow 

3. 8. 3.1  Original  manuscript  will  be  typewritten  on  vellum  to 
facilitate  ozalld  or  equivalent  reproduction.  Orange  backing  Is 
not  required  but  Is  acceptable.  Manuscript  shall  be  single  spaced. 

A 3/4"  margin  (approximately)  shall  be  maintained  on  all  edges. 

3.8.4  Functional  Specification 

3. 8.4.1  Upon  completion  of  the  design  review  and  Incorporation  of 
all  changes  and  comments  resulting  from  design  review,  the  Program 
Plow  Diagrams  and  the  functional  description  shall  be  combined  and 
renamed  Functional  Specification.  Identifying  n\mibers  shall  be 
provided  by  the  contracting  agency. 

3. 8. 4. 2 Final  Copies.  Final  copies  shall  be  ozalld  or  equivalent 
reproductions  of  the  text  of  the  functional  descriptions.  Right- 
hand  margins  shall  be  lanjustifled.  Proportionate  spacing  type- 
writers with  a 12-point  sans  serif  demibold  type  face  are  preferred; 
however,  clean,  legible,  type  from  any  typewriter  is  acceptable. 

The  Program  Flow  Diagrams  shall  be  Inserted  immediately  following 
the  corresponding  sections  of  text.  The  diagrams  In  the  Functional 
Specification  shall  be  ozalld  or  equivalent  reproductions  of  reduced 
film  (paper  or  acetate)  copies  of -the  Program  Plow  Diagram.  Two- 
to-one  reduction  provides  the  transition  from  the  original  art  size 
to  11"  X length  fold-out  size  which  Is  compatible  with  the  text 
pages. 

3.8.5  Listings 

3. 8. 5.1  To  be  discussed. 

3.8.6  Functional  Flow  Charts 

3.8.6. 1 Since  Functional  Plow  Charts  may  be  prepared  by  either  of 
two  techniques  the  format  will  depend  on  the  technique  chosen. 

3. 8. 6. 2 Machine  Prepared  Functional  Flow  Charts.  Machine  prepared 
Functional  Flow  Charts  shall  be  offset  reproductions  of  the  computer 
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printout.  The  machine  printout  shall  be  photoreduced  to  50  percent. 
The  paper  stock  shall  be  80-pound  bondj  binding  shall  be  in  accord- 
ance with  3.8.7. 

3. 8. 6. 3 Manually  Prepared  Functional  Flow  Charts.  Manually- 
prepared  Functional  Flow  Charts  shall  be  offset  reproductions  of  the 
photoreduced  charts.  Paper  stock  shall  be  80-poTind  bond.  Binding 
shall  be  in  accordance  with  3.8.7. 

3.8.7  Binding 

3. 8. 7.1  Functional  Descriptions  of  Logic  Flow  and  Functional 
Specification  shall  be  prepared  in  looseleaf  form  to  facilitate  the 
insertion  of  replacement  pages.  For  manuals  of  less  than  1/2-lnch 
thickness,  commercial  metal  fasteners  are  to  be  used.  The  pages 
shall  be  punched  or  drilled  as  follows  (all  eimenslons  in  Inches): 

Hole-type  binders  8-1/4  x 10-3/4 

Number  of  holes  3 

Hole  size  1/4 

Distance,  center  to  center  4 
Distance  to  binding  edge  7/16 


Distance,  center  to  center 
Distance  to  binding  edge 


3. 8. 7. 2 For  manuals  that  exceed  approximately  1/2-inch  thickness, 
looseleaf  mechanical  opening  three-ring  binding  shall  be  used. 
Punching  or  drilling  of  revision  pages  shall  be  the  same  as  for  the 
original  manuals. 

3.8.8  Paper  and  Cover  Stock 

3. 8. 8.1  Any  good-quality  paper  stock  which  is  suitable  for  the 
Intended  method  of  reproduction  will  be  satisfactory  for  text  and 
fold-ln  pages.  Cover  stock  satisfactory  for  the  intended  use  is 
acceptable;  however,  the  color  shall  conform  to  security 
requirements . 

3.8.9  Security  Classification 

3.8.9. 1 The  security  classification  of  a drawing  shall  be  as 
designated  by  the  bureau  or  agency  concerned.  The  Security 
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Requirements  Check  List  (DD  Form  254),  which  constitutes  a part  of 
the  contract  for  all  classified  material.  Identifies  and  Indicates 
the  classified  features.  All  pages  of  classified  manuals  and  sup- 
plements shall  be  marked  in  accordance  with  the  Industrial  Security- 
Manual  for  Safeguarding  Classified  Information. 

3.8. 9.2  Additional  Security  Markings.  Vfhen  a manual  contains 
information  of  a higher  classification  than  that  of  the  equipment 
it  concerns,  the  appropriate  classification  of  all  classified  data 
contained  within  that  manual  shall  be  identified  by  a classification 
letter (s)  enclosed  in  parentheses  and  positioned  as  follows: 

(a)  At  the  beginning  and  end  of  paragraphs  and  subparagraphs. 

(b)  At  the  end  of  the  subject  or  title. 

3*8. 9*3  Classification  Letters.  The  classification  letters 
assigned  to  the  various  levels  are:  (TS)  Top  Secret,  (S)  Secret, 

(C)  Confidential,  (CMH)  Confidential  — Modified  Heuidllng  Authorized, 
(CRD)  Confidential  — Restricted  Data,  and  (NOPORN)  No  Foreign 
Nationals.  Although  it  is  not  intended  that  each  and  every  item  of 
Information  bear  a classification  letter,  the  letter  (U)  shall  be 
used  as  directed  by  the  bureau  or  agency  concerned  to  denote 
unclassified  data. 

3.8.10  Notes,  Cautions,  and  Warnings 

3.8.10,1  Notes,  cautions,  and  warnings  shall  be  used  to  emphasize 
important  and  critical  instructions,  consistent  with  the  need. 

Notes,  cautions,  and  warnings  shall  immediately  precede  the  appli- 
cable instructions,  and  shall  be  selected  in  accordance  with  the 
following : 

(a)  "NOTE"  - Concerns  an  operating  procedure  or  condition 
which  should  be  highlighted. 

(b)  "caution"  - Concerns  an  operating  procedure  or  practice, 
which  if  not  strictly  observed,  will  result  in  damage  to  or  destruc- 
tion of  equipment. 

(c)  "warning"  - Concerns  an  operation  procedure  or  practice 
which,  if  not  strictly  observed,  will  result  in  injury  to  personnel 
or  loss  of  life. 


3-42 


3.8.11  Numbering  and  Identification 


3.8.11.1  The  subordinated  numbering  of  the  Program  Plow  Diagrams 
shall  be  the  basis  for  numbering  all  associated  doc\unents.  The 
Program  Plow  Diagram  for  the  complete  program  shall  be  Identified 
as  0.0.  Each  major  routine  Identified  on  this  diagram  shall  be 
numbered  consecutively  beginning  with  1.  The  Program  Plow  Diagram 
for  each  of  the  routines  Illustrated  on  the  complete  program  dia- 
gram shall  carry  the  Identifying  number  provided  on  the  Program 
Plow  Diagram  for  the  computer  program.  Subroutines  illustrated  on 
these  diagrams  shall  be  numbered  beginning  with  1. 

3.8.11.2  The  Program  Plow  Diagram  for  each  subroutine  shall  carry 
the  same  type  of  identifying  number.  Subordinate  groupings  within 
the  diagram  shall  be  numbered  according  to  the  same  indenture  scheme. 

3.8.11.3  The  Functional  Description  and  Functional  Specification 
paragraph  numbering  system  shall  provide  a one-to-one  reference 
between  the  Program  Plow  Diagrams  and  the  associated  text. 
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4.  QUALITY  ASSURANCE 


4.1  Accuracy  and  completeness  are  the  criteria  for  acceptance  of 
computer  program  doc\imentationj  format  Is  a consideration.  It  is 
presumed  that  quality  assurance  is  an  inherent  part  of  all  contract- 
ing organizations.  The  responsibility  of  PCPC  is  to  check  the 
effectiveness  of  the  quality  control  organization  at  the  contractor 
facility,  rather  than  to  be  responsible  for  the  quality  of  the  end 
product.  The  Quality  Assurance  Monitor  Policy  described  in  this 
section  provides  guidelines  to  the  contractor  for  quality  control 
programs  to  assure  end  products  of  acceptable  quality. 

4.2  FCPC  will  Implement  quality  control  Insurance  checks  by 
performing  a detailed  quality  control  inspection  on  a random  sample 
basis,  as  described  in  the  following  paragraphs.  All  documents  of 
the  same  type  (l.e.,  program  flow  diagrams,  listings,  etc.)  will  be 
deemed  to  be  equally  acceptable  or  vinacceptable  as  the  sample  taken. 

4.3  OPERATIONAL  SPECIFICATION  - PROGRAM  FLOW  BLOCK  DIAGRAMS 

4.3.1  A check  will  be  performed  to  ensure  that  the  requirements  of 
the  Operational  Specifications  are  satisfied.  Logic  Flow  Block  Dia- 
grams will  also  be  checked  for  adequate  and  logical  subfunctional 
groupings . 

4.4  PROGRAM  PLOW  BLOCK  DIAGRAM  - FUNCTIONAL  SPECIFICATION 

4.4.1  The  Functional  Description  will  be  checked  against  the  block 
diagram  to  ensure  compatibility  of  numbering,  text  coverage  of  each 
block,  and  the  technical  adequacy  of  the  paragraph  describing  the 
related  block  on  the  Program  Flow  Diagram. 

4.5  FUNCTIONAL  SPECIFICATION  - PROGRAM  ASSEMBLY  LISTING 

4.5.1  A check  will  be  made  of  the  adequacy  and  accuracy  of  the 
comments  placed  in  the  listing  resulting  from  the  comment  cards 
developed  during  the  programming  process.  The  actual  programming 
technique  shall  be  checked  for  good  programming  practice. 
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4.6  FUNCTIONAL  PLOW  CHART  DIAGRAMS  - TESTING  ROUTINE 


4.6.1  “nie  testing  routine  shall  be  checked  against  the  Functional 
Flow  Charts  to  ensure  that  the  logic  Is  exercised  completely  and 
that  the  testing  routine  does  test  the  performance  of  the  subroutine, 
routine,  or  program. 

4.7  The  objective  of  quality  control  is  to  provide  near-perfect 
documentation,  not  to  critlciae  human  frailty.  Discrepancies  found 
by  FCPC  personnel  will  be  graded  into  three  categories  as  follows: 

(a)  Critical  - Mandatory  correction 

(b)  Secondary  - Improvement  to  be  made  next  revision 

(c)  Minor  - Correction  to  be  made  when  page  is  revised 

(typo,  misspelling) 

To  preclude  double  retyping  to  Incorporate  both  FCPC  and  contractor 
comments,  pencil-marked  copy  may  be  submitted  by  the  contractor  to 
FCPC  for  final  quality  control  Inspection. 
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5.  PREPARATION  FOR  DELIVERY 


5.1  PACKAGING  AND  PACKING 

5.1.1  All  items  shall  he  packed  to  preclude  the  possibility  of 
damage  in  transit.  Multivolume  manuals  shall  be  furnished  as  com- 
plete sets  except  for  the  manuals  shipped  for  stock.  Stock  copies 
of  identical  volumes  shall  be  packed  and  shipped  in  common 
container (s ) . 

5.1.2  Bulk  Shipment 

5. 1.2.1  Data  items  shipped  in  bulk  shall  not  be  Individually 
wrapped.  Containers  shall  comply  with  the  Uniform  Freight  Classi- 
fication Rules,  or  other  regulations  applicable  to  the  mode  of 
transportation. 

5.1.3  Marking 

5. 1.3.1  On  bulk  shipments,  interior  packages  and  exterior  shipping 
containers  shall  be  marked  with  the  following  Information  for  each 
item  enclosed. 

(a)  Box  (number)  of  (number) — to  be  shown  on  each  container 
for  multiple  container  shipments. 

(b)  Publication  nvunber. 

(c)  Quantity  (in  package). 

(d)  Contract  or  order  number. 

5. 1.3.2  The  words  "FOR  STOCK”  shall  be  marked  on  the  package  or 
packages  destined  for  stock.  The  publication  nrmbers  shall  be  Indl 
cated  on  the  shipping  documents. 
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6.  NOTES 


6.1  ORDERING  DATA 

6.1.1  Procurement  documents  shall  specify  the  following: 

(a)  Title  and  number  of  specification. 

(b)  Security  classification. 

(c)  Quantity  of  manuals  (revisions  of  APR  pages ),  supplements 
and  preventative  maintenance  data  required. 

6.2  LIABILITY  NOTICE 

6.2.1  When  Government  drawings,  specifications,  or  other  data  are 
used  for  any  purpose  other  than  in  connection  with  a definitely 
related  Government  procurement  operation,  the  United  States  Govern- 
ment thereby  Incurs  no  responsibility  nor  any  obligation  whatsoever, 
and  the  fact  that  the  Government  may  have  formulated,  furnished,  or 
in  any  way  supplied  the  said  drawings,  specifications,  or  other  data 
is  not  be  be  regarded  by  implication  or  otherwise  as  in  any  manner 
licensing  the  holder  or  any  other  person  or  corporation,  or  con- 
veying any  rights  or  permission  to  manufacture,  use,  or  sell  any 
patented  Invention  that  may  in  any  way  be  related  thereto. 
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